package com.smart.community.region.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.region.dto.OwnerDTO;
import com.smart.community.region.dto.OwnerUpdateDTO;
import com.smart.community.region.dto.OwnerQueryDTO;
import com.smart.community.region.entity.Owner;
import com.smart.community.region.vo.OwnerVO;
import com.smart.community.region.vo.OwnerEditVO;

import java.util.List;

import com.smart.community.region.dto.OwnerStatisticsDTO;

/**
 * 业主服务接口
 * 
 * @author Wu.Liang
 * @since 2025-08-20
 * @version 1.0.0
 */
public interface IOwnerService extends IService<Owner> {
    
    /**
     * 分页查询业主列表
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     * @throws Exception 统一异常
     */
    IPage<OwnerVO> getOwnerPage(OwnerQueryDTO queryDTO) throws Exception;
    
    /**
     * 根据ID查询业主详情
     * 
     * @param id 业主ID
     * @return 业主详情
     * @throws Exception 统一异常
     */
    OwnerVO getOwnerById(Long id) throws Exception;
    
    /**
     * 根据ID查询业主编辑数据（包含原始数据，不脱敏）
     * 
     * @param id 业主ID
     * @return 业主编辑数据
     * @throws Exception 统一异常
     */
    OwnerEditVO getOwnerEditById(Long id) throws Exception;
    
    /**
     * 创建业主
     * 
     * @param dto 业主信息
     * @return 业主ID
     * @throws Exception 统一异常
     */
    Long createOwner(OwnerDTO dto) throws Exception;
    
    /**
     * 更新业主信息
     * 
     * @param id 业主ID
     * @param dto 业主信息
     * @throws Exception 统一异常
     */
    void updateOwner(Long id, OwnerDTO dto) throws Exception;
    
    /**
     * 更新业主信息
     * 
     * @param id 业主ID
     * @param dto 业主信息
     * @throws Exception 统一异常
     */
    void updateOwner(Long id, OwnerUpdateDTO dto) throws Exception;
    
    /**
     * 删除业主
     * 
     * @param id 业主ID
     * @throws Exception 统一异常
     */
    void deleteOwner(Long id) throws Exception;
    
    /**
     * 批量删除业主
     * 
     * @param ids 业主ID列表
     * @throws Exception 统一异常
     */
    void batchDeleteOwners(List<Long> ids) throws Exception;
    
    /**
     * 根据用户ID查询业主
     * 
     * @param userId 用户ID
     * @return 业主信息
     * @throws Exception 统一异常
     */
    Owner getOwnerByUserId(Long userId) throws Exception;
    
    /**
     * 根据身份证号查询业主
     * 
     * @param idCard 身份证号
     * @return 业主信息
     * @throws Exception 统一异常
     */
    Owner getOwnerByIdCard(String idCard) throws Exception;
    
    /**
     * 根据手机号查询业主
     * 
     * @param phone 手机号
     * @return 业主信息
     * @throws Exception 统一异常
     */
    Owner getOwnerByPhone(String phone) throws Exception;
    
    /**
     * 根据房户ID查询关联的业主列表
     * 
     * @param householdId 房户ID
     * @return 业主列表
     * @throws Exception 统一异常
     */
    List<Owner> getOwnersByHouseholdId(Long householdId) throws Exception;
    
    /**
     * 根据社区ID查询业主列表
     * 
     * @param communityId 社区ID
     * @return 业主列表
     * @throws Exception 统一异常
     */
    List<Owner> getOwnersByCommunityId(Long communityId) throws Exception;
    
    /**
     * 根据楼栋ID查询业主列表
     * 
     * @param buildingId 楼栋ID
     * @return 业主列表
     * @throws Exception 统一异常
     */
    List<Owner> getOwnersByBuildingId(Long buildingId) throws Exception;
    
    /**
     * 根据单元ID查询业主列表
     * 
     * @param unitId 单元ID
     * @return 业主列表
     * @throws Exception 统一异常
     */
    List<Owner> getOwnersByUnitId(Long unitId) throws Exception;
    
    /**
     * 检查身份证号是否已存在
     * 
     * @param idCard 身份证号
     * @param excludeId 排除的业主ID
     * @return 是否存在
     * @throws Exception 统一异常
     */
    boolean checkIdCardExists(String idCard, Long excludeId) throws Exception;
    
    /**
     * 检查手机号是否已存在
     * 
     * @param phone 手机号
     * @param excludeId 排除的业主ID
     * @return 是否存在
     * @throws Exception 统一异常
     */
    boolean checkPhoneExists(String phone, Long excludeId) throws Exception;
    
    /**
     * 获取业主统计信息
     * 
     * @return 统计信息
     * @throws Exception 统一异常
     */
    OwnerStatisticsDTO getOwnerStatistics() throws Exception;
}
